Welcome to EOELAB!

EOELAB 互联云架构规范

EOELAB 互联云架构规范

本文档定义 EOELAB 互联云是什么、由哪些实体组成、必须满足哪些约束与规范。

阅读导览

RFC-0001 引言

系统模型

EOELAB 互联云是一个本地域优先的联邦计算系统，其核心观点是：

联邦系统基于以下默认假设构建：

  1. 底层网络不可信 —— 公网和物理网络上的通信可能被监听，跨节点通信统一由 Tailscale 加密
  2. 联邦网络可信 —— 有效 Zitadel 账户可以直接接入 Headscale，成员节点默认获得联邦网络连通性
  3. 网络与服务分层 —— 网络连通性不等同于应用资源权限，服务继续执行自身必要的认证、授权和数据边界
  4. 响应式治理 —— 不以复杂的事前审核和网络微隔离代替治理，管理员在实际滥用发生后暂停账户、移除节点或撤销凭证
  5. 本地域自负责 —— 自身资源与业务数据的最终责任在本地域

协作原则

我们是一个面向联邦基础设施与自治系统的技术社区。

我们鼓励：

我们不接受：

核心实体

  1. 本地域：基于 Incus 的自治计算域，拥有独立的控制面、调度能力和资源责任（VM、LXC、OCI 同层调度）
  2. 本地服务设备：加入联邦并提供服务，但不具备自治能力的节点
  3. 本地设备：加入联邦只访问且不提供服务的设备

RFC-0002 本地域

本地域由唯一 Incus 控制面、调度域、故障域和维护责任域定义，不由物理子网定义，并能独立对外提供服务。

本地域可以架构为：

  1. 单Incus节点
  2. 集群：同一本地域内的节点组成的集合，满足：
    • 存在三个及以上Incus节点组成集群
    • 节点通过联邦网络低延迟直连
    • 数据设施接口一致

注：双节点只能作为两个独立的单节点管理，不得建立集群。

核心本地域

  1. 核心本地域（coreNumber命名）是由 admin 团队长期维护、持续提供公共服务能力的本地域，这是为了保证 EOELAB 社区与联邦生态具备长期持续运行能力
  2. 核心本地域会额外承担被托管服务，即服务所有者没有设备/没有找到可信维护者托管：
    • 核心本地域将存储业务数据，并提供服务
    • 尽管 admin 团队承诺绝不泄露数据，但建议业务自行实现端到端加密或主机不可解密的数据保护机制，避免意外泄露
  3. 由于资源限制，核心本地域可能根据资源情况限制服务接入
  4. 有效 Zitadel 用户账户即代表成员身份并可接入联邦网络；应用管理权限和资源权限统一遵循《EOELAB 权限模型》

RFC-0003 计算设施

运行时

类型技术定位说明
虚拟化KVM（VM）需要内核特权时的特殊运行时有性能损失与额外负担，启动较慢
系统层容器LXC标准运行时仅支持 Linux，禁止特权容器
应用层容器OCI服务运行时常规 OCI 容器

节点配置

配置项要求
主机名Incus 节点使用 DomainPrefix-Number，DomainPrefix 为联邦内唯一的本地域标识，Number 从 1 开始；例如 core0-1
节点寻址统一使用 HOSTNAME.eoelab
根文件系统Btrfs，使用 raid1/10 作为数据冗余策略
登录方式仅支持 SSH 密钥登录，禁止使用密码验证
操作系统Debian stable + Incus stable（https://github.com/zabbly/incus）
时间同步Debian stable 默认通过 systemd-timesyncd 维持 UTC 同步，无需额外配置 NTP
swap禁用 swap，以保证性能可预期/避免挤兑存储系统

嵌套 OCI 容器

特指在 LXC 运行时里嵌套运行 OCI 容器。由于 lxcfs 仅为 LXC 模拟了 procfs 和 sysfs，但嵌套容器会绕过 lxcfs 直接读取宿主机内存容量。由于 Incus 已支持 OCI 调度，默认不允许嵌套；CI/CD 中使用 Kaniko 构建镜像为例外。

鉴权

RFC-0004 数据设施

存储接口

接口是最终暴露在计算设施中的数据入口，由存储服务接口与存储介质评级拼接。计算设施只消费块设备和文件系统接口：

字段含义取值
接口类型数据入口语义bs：块设备；fs：文件系统
介质磁盘协议h：SAS/SATA HDD；s：SAS/SATA SSD；n：NVMe SSD
容量容量等级s：≤1T；m：1–4T；l：4–12T；e：>12T
性能性能等级h：更好；m：居中；l：最差（初始设备一般分配 l）
拼接格式<接口类型>_<介质><容量><性能>例：fs_nml = 文件系统 / NVMe / 1–4T / 性能 l

注意：集群必须保证各节点数据接口一致，保证集群可以重平衡实例，但本地存储不支持集群自愈合。

数据温度

类型访问特征典型场景I/O 模式
热数据高频访问，延迟敏感，吞吐量要求高数据库、缓存、实时计算、在线服务随机读写多，写密集
温数据中等频率访问，延迟可容忍数十ms共享文件、CI/CD 产物、容器镜像、日志存储顺序读写多，写较少
冷数据低频访问，延迟不敏感，保留成本优先备份、归档、合规保留、快照极少读，几乎不写

数据保护策略

策略容错能力驱动支持容量适用场景主要缺点
多副本允许 N-1 丢失Btrfs/TrueNAS/Ceph1/N热数据、延迟敏感、故障恢复要求快存储利用率低
RAID-Z允许 Z1/Z2 分别 1/2 盘丢失TrueNASZ1: N-1/N；Z2: N-2/N温/冷数据、大容量、写入频率低写入性能差、重建慢且风险高
纠删码（EC）允许任意 M 块丢失CephK/K+M大规模/大容量、读取多写入有编码开销、小文件放大

数据管理策略

  1. 热数据无论如何都用多副本，性能优先，恢复快，不引入编码开销；最小副本数：Btrfs/TrueNAS 为 2，Ceph 为 3
  2. 温/冷数据根据底座选择编码方式：TrueNAS 用 RAID-Z（Z2 优先，容量受限才用 Z1）；Ceph 用 EC（温数据 4+2，冷数据 8+3 或更高；磁盘极少时用多副本避免小文件放大）
  3. 对于典型 SSD/HDD 混合场景，遵循“显式配置优于缓存”原则，将相同介质与性能等级的磁盘组池而不使用分层缓存
  4. 多节点部署优先采用计算与存储分离架构；仅在可接受停机、临时高负载或数据与计算强绑定场景使用本地存储

存储驱动

底座接口适用规模说明
Btrfsfs本地存储节点本地提供
TrueNASbs单机/小/中规模（3–6 节点）命名为 DomainPrefix-nas；不支持双机
Cephbs/fs大/超大规模（≥7 节点）独立节点命名为 DomainPrefix-ceph-Number；EC 4+2 起步

Ceph 架设方式：

  1. 与计算设施聚合为超融合设施（当存储高负载、与计算扩容比例失衡、或与计算争用资源时，考虑独立集群）
  2. 独立 Ceph 集群

Ceph 节点和客户端统一使用 .eoelab 节点名称通信。

RFC-0005 网络设施

EOELAB 只定义两层网络能力：

  1. 联邦网络：所有节点之间的统一通信层，承载节点管理、集群心跳、存储复制和服务通信
  2. 实例虚拟网络：使用 bridge/OVN 提供实例接入和实例间互联，由 Incus 管理 ACL、NAT、地址、隔离和流量策略

底层网络只需为 Tailscale 提供 IP 连通性，不作为本地域的独立架构设施。节点不需要为集群通信配置静态局域网地址、局域网 DNS 或 hosts 映射。

服务接入与传输安全

  1. Tailscale 是联邦网络设施，负责节点身份绑定、寻址、连通性以及信道的机密性与完整性
  2. 联邦成员节点默认可以发现并连接其他联邦节点，不使用复杂的成员分级或网络微隔离重复实现应用权限
  3. 联邦内部服务统一通过 .eoelab 访问，应用协议默认不配置 TLS，不单独维护服务端证书或客户端 TLS
  4. 服务按用途明确选择公网或联邦网络用户入口，不要求同时提供两类入口；Cloudflare Tunnel 只承载批准的公网 HTTP/HTTPS 入口，源站使用 localhost 或 .eoelab HTTP 地址
  5. 服务必须保留自身必要的安全边界，不使用弱密钥、匿名写入或未经明确决定的 Public 资源；数据库账户、OIDC、Token、OpenFGA 和 RustFS Policy 等机制不因位于联邦网络而取消
  6. 内部服务通信、集群心跳和存储复制只使用联邦网络，不得因存在公网管理入口而改走公网
  7. 应用明文流量不得离开 Tailscale 或 Cloudflare Tunnel；其他路径必须单独加密
  8. 非 HTTP/HTTPS 服务不向公网开放，只允许通过联邦网络访问
  9. Incus Web UI 和 RustFS Console 只提供公网管理入口；Incus 节点直连、RustFS S3 和 WebDAV 只提供联邦网络入口

虚拟网络架设

  1. 默认仅启用 IPv4 NAT 网络；IPv6 属于可选能力而非默认要求
  2. 单节点使用 bridge，集群使用 ovn, 整个本地域有且仅有一个虚拟网络,命名为INTERFACE-Domain
  3. 地址池默认使用 172.16.0.0/12
  4. 实例网络接入设备默认 eth0；VM 在需要 proxy 设备时可设置静态地址
  5. 实例使用 proxy 设备做端口转发以暴露服务
  6. SR-IOV 仅在明确高性能网络需求（如 GPU RDMA、特定 HPC 场景）时考虑，不作为标准网络设施

ACL 规则

ACL 用于约束虚拟网络行为。

最终策略包含多个ACL规则的组合： * 例如只希望访问互联网：放行所有出入站流量，丢弃私网出入站流量（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16），使实例只能访问互联网而不能互相访问/连接。

RFC-0006 联邦设施

为了克服本地域权限模型重复、无公网设备互联难度大等问题，通过联邦控制设施构建联邦计算系统。

联邦设施包括：

联邦设施
├── 联邦控制设施
│   ├── 数据库
│   ├── 认证设施
│   ├── 授权设施
│   └── 网络设施
├── 原生设施
│   ├── 对象存储服务
│   ├── 自托管Runner
│   └── 监控设施
└── 集成设施
    ├── 镜像仓库
    ├── 协作设施
    └── 公告设施

联邦控制设施

联邦控制设施作为持续在线的控制面运行，公网入口由 Cloudflare Tunnel 提供，状态数据保留为可重建备份。

数据库

仅用于支持联邦设施，不对业务开放。

认证设施

通过统一的认证设施避免重复认证/自托管密钥库。

认证策略

EOELAB 认证策略采用“平台原生凭证优先，外部 IDP 增强为辅”的并行模型：

授权模型

Zitadel 账户直接提供成员身份。应用需要区分资源或管理能力时使用自身授权机制，具体边界统一参见《EOELAB 权限模型》。

授权设施

Zitadel 仅支持 RBAC 权限模型，额外基于 OpenFGA 提供 ReBAC 权限模型。

框架

组件框架说明
授权服务OpenFGA各域独立实例
控制面fgaplane模型读写、Tuple 增删、授权诊断

具体地址统一参见《EOELAB 服务端点》。

网络设施

  1. 联邦网络采用节点级 MESH 模型，节点间基于访问策略建立点对点加密 WireGuard 隧道
  2. 节点优先直接连接，无法直连时通过 DERP 中继；集群心跳和存储复制应保持直连
  3. Headscale 负责节点注册、密钥、节点信息和策略下发，不承载业务流量；在已有网络状态有效期间，Headscale 暂时离线不应中断已有通信
  4. 使用 Headscale 标准的 CGNAT 网段：
    • IPv4: 100.64.0.0/10
    • IPv6: fd7a:115c:a1e0::/48
  5. 联邦网络默认提供成员节点之间的网络连通性；服务资源权限由服务自身管理
  6. 不得使用反向代理/隧道穿透工具将未批准的联邦网络内部端点映射到公网节点上暴露
  7. .eoelab 是联邦网络内部域名，根据节点主机名自动生成记录

框架

组件框架说明
控制节点Headscale禁用内置 DERP 服务器
WebUIHeadplane节点、用户和网络策略管理
中继服务DERP供应商与社区节点
公网入口Cloudflare Tunnel为批准的公网服务管理 DNS 路由和边缘 TLS，不属于联邦网络数据平面

具体地址统一参见《EOELAB 服务端点》。

原生设施

对象存储服务

自托管 Runner

通用 runner

tag 策略：[size, arch, runtime]

size内存
tiny2–4G
small4–8G
medium8–16G
archruntime
amd64lxc：轻量运行时，非特权，部分操作受限
riscv64vm：标准运行时，拥有特权内核

节点预装 git。优先考虑非特权方案：OCI 容器打包使用 kaniko，OCI 镜像操作使用 crane，拒绝 dind 和 docker 操作 registry。

专用 runner

tag 策略：[purpose]，用于特定用途而非通用构建。例如 mirror：位于海外，负责镜像中国大陆无法访问的 OCI 镜像/软件包。

当前活跃

规格数量
medium amd64 vm1
mirror1

监控设施

监控设施采用存算分离架构，本地保留 WAL、短期数据和缓存，历史指标和日志存入 oss。

用途框架说明
全联邦指标采集Prometheus在 monitor 采集联邦节点和服务指标、短期存储并执行告警规则
指标长期存储与联邦查询Thanos将不可变指标块存入 RustFS，并提供跨地域查询
可视化Grafana状态存入联邦 PostgreSQL，仪表盘和数据源优先配置化管理
日志Loki使用 TSDB Single Store，将日志块和索引存入 RustFS
历史指标告警Thanos Ruler评估依赖历史指标的规则
告警通知Alertmanager使用本地快照和 Gossip 保持通知与静默状态

集成设施

镜像仓库

VM/LXC 仓库

使用官方仓库（images.linuxcontainers.org）。不在该仓库内的 OS 视同放弃。

OCI 仓库

Docker Hub 镜像通过《EOELAB 服务端点》列出的镜像入口拉取。该入口受 Docker Hub 和 Cloudflare Worker 拉取额度限制，必须使用 Docker Hub 账户登录，不提供匿名拉取。

使用阿里云容器镜像仓库（crpi-0fzeutaz68uv7lwt.cn-hangzhou.personal.cr.aliyuncs.com/NAMESPACE/REPO）：

OCI 仓库不公开密钥，所有操作通过 Codeberg 仓库的 Actions 完成。

协作设施

EOELAB 使用 QQ 即时通信群组用于联邦协作：协调运维、通知故障/安全事件、日常交流。暂不考虑自建 Matrix。

公告设施

域名：www.eoelab.org

由 Codeberg Actions 基于 Zine 框架自动构建，并作为静态资产发布至 Cloudflare Workers，用于发布社区公共通知、联邦规范与文档、服务端点/状态变更、基础设施/维护/安全事件公告。

公共联系方式

我们暂不考虑自建邮件服务器或强行聚合为 NAME@eoelab.org。

Post list